---
title: User permissions
---

import TierLabel from "../_components/TierLabel";

This is an explanation of the [kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
needed by users of the Weave GitOps application. As covered in
[service account permissions](service-account-permissions.mdx)
the primary way that the application interacts with the Kube API is via [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation).
This means that the permissions granted to the users and groups that Weave GitOps
can impersonate determine the scope of actions that it can take within your cluster.

A minimal set of permissions are generated for the static cluster-user as part
of the [helm chart](https://github.com/weaveworks/weave-gitops/tree/main/charts/gitops-server/templates/admin-user-roles.yaml).

By default both a ClusterRole and Role are generated for the static cluster-user.
Both have the same permissions with former being optional and the latter being
bound to the `flux-system` namespace (where Flux stores its resources by default).
The default set of rules are configured like this:
```yaml
rules:
  # Flux Resources
  - apiGroups: ["source.toolkit.fluxcd.io"]
    resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
    verbs: [ "get", "list", "watch", "patch" ]

  - apiGroups: ["kustomize.toolkit.fluxcd.io"]
    resources: [ "kustomizations" ]
    verbs: [ "get", "list", "watch", "patch" ]

  - apiGroups: ["helm.toolkit.fluxcd.io"]
    resources: [ "helmreleases" ]
    verbs: [ "get", "list", "watch", "patch" ]

  - apiGroups: [ "notification.toolkit.fluxcd.io" ]
    resources: [ "providers", "alerts" ]
    verbs: [ "get", "list", "watch", "patch" ]

  - apiGroups: ["infra.contrib.fluxcd.io"]
    resources: ["terraforms"]
    verbs: [ "get", "list", "watch", "patch" ]

  # Read access for all other Kubernetes objects
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: [ "get", "list", "watch" ]
```


### Flux Resources

The resources that Flux works with directly, including the one from TF-controller.

| Api Group                      | Resources                                                               | Permissions      |
| ------------------------------ | ----------------------------------------------------------------------- | ---------------- |
| kustomize.toolkit.fluxcd.io    | kustomizations                                                          | get, list, patch |
| helm.toolkit.fluxcd.io         | helmreleases                                                            | get, list, patch |
| source.toolkit.fluxcd.io       | buckets, helmcharts, gitrepositories, helmrepositories, ocirepositories | get, list, patch |
| notification.toolkit.fluxcd.io | providers, alerts                                                       | get, list        |
| infra.contrib.fluxcd.io        | terraforms                                                              | get, list, patch |

In order for Weave GitOps to be able to accurately display the state of Flux it
needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses. This is done using the
`get` and `list` permissions

The `patch` permissions are used for 2 features: to suspend and resume
reconciliation of a resource by modifying the 'spec' of a resource,
and to force reconciliation of a resource by modifying the annotations
of the resource. These features work the same way `flux suspend`,
`flux resume` and `flux reconcile` does on the CLI.

### Resources managed via Flux

| Api Group                 | Resources                                                                      | Permissions      |
|---------------------------|--------------------------------------------------------------------------------|------------------|
| ""                        | configmaps, secrets, pods, services, persistentvolumes, persistentvolumeclaims | get, list, watch |
| apps                      | deployments, replicasets, statefulsets                                         | get, list, watch |
| batch                     | jobs, cronjobs                                                                 | get, list, watch |
| autoscaling               | horizontalpodautoscalers                                                       | get, list, watch |
| rbac.authorization.k8s.io | roles, clusterroles, rolebindings, clusterrolebindings                         | get, list, watch |
| networking.k8s.io         | ingresses                                                                      | get, list, watch |

Weave GitOps reads basic resources so that it can monitor the effect that Flux has
on what's running.

Reading `secrets` enables Weave GitOps to monitor the state of Helm releases
as that's where it stores the [state by default](https://helm.sh/docs/faq/changes_since_helm2/#secrets-as-the-default-storage-driver).
For clarity this these are the Helm release objects _not_ the Flux HelmRelease
resource (which are dealt with by the earlier section).

### Feedback from Flux

The primary method by which Flux communicates the status of itself is by events,
these will show when reconciliations start and stop, whether they're successful
and information as to why they're not.

## Weave GitOps Enterprise <TierLabel tiers="enterprise" />

Weave GitOps Enterprise extends Weave GitOps OSS by adding more roles. These roles may need to be extended further in order to support certain use cases. Some of the most common use cases are described below.

### Progressive delivery with Flagger

Weave GitOps Enterprise integrates with Flagger in order to provide a view on progressive delivery deployments. This includes the ability to view all the resources that Flagger manages during its operation. The default ClusterRole `gitops-canaries-reader` includes the minimum permissions necessary for a user to be able to view canary object details, metric template object details and canary related events. 

When Flagger is configured to integrate with a service mesh such as Linkerd or Istio for the rollout, then this ClusterRole needs to be extended so that it can read the additional service mesh resources being generated by Flagger. Note that currently, in order to display service mesh or ingress related resources, we require `spec.provider` to be set in each canary resource. 

The following table provides a list of all the custom resources that Flagger generates grouped by provider:

| Provider          | API Group                 | Resource        |
| ---               | ---                       | ---             |
| AppMesh           | appmesh.k8s.aws           | virtualnode     |
|                   | appmesh.k8s.aws           | virtualrouter   |
|                   | appmesh.k8s.aws           | virtualservice  |
| Linkerd           | split.smi-spec.io         | trafficsplit    |
| Istio             | networking.istio.io       | destinationrule |
|                   | networking.istio.io       | virtualservice  |
| Contour           | projectcontour.io         | httpproxy       |
| Gloo              | gateway.solo.io           | routetable      |
|                   | gloo.solo.io              | upstream        |
| Nginx             | networking.k8s.io         | ingress         |
| Skipper           | networking.k8s.io         | ingress         |
| Traefik           | traefik.containo.us       | traefikservice  |
| Open Service Mesh | split.smi-spec.io         | trafficsplit    |
| Kuma              | kuma.io                   | trafficroute    |
| GatewayAPI        | gateway.networking.k8s.io | httproute       |

For example, the following manifest shows how `gitops-canaries-reader` has been extended to allow the user for viewing TrafficSplit resources when Linkerd is used:

```yaml title="gitops-canaries-reader.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gitops-canaries-reader
rules:
- apiGroups:
  - flagger.app
  resources:
  - canaries
  - metrictemplates
  verbs:
  - get
  - list
- apiGroups:
  - ""
  resources:
  - events
  verbs:
  - get
  - watch
  - list
# Additional permissions for Linkerd resources are added below
- apiGroups:
  - split.smi-spec.io
  resources:
  - trafficsplits
  verbs:
  - get
  - list
```

#### Setting up remote cluster permissions

In order to view canaries in a remote cluster from the management cluster, you need to consider the following:
- The service account used to access the remote cluster needs to be able to list namespaces and custom resource definitions in the given cluster. It additionally needs to be able to impersonate users and groups.
- The user or group that logs in to the management cluster, needs appropriate permissions to certain resources of the remote cluster.

For example, applying the following manifest on remote clusters, ensures that the `wego-admin` user will be able to view canary information from within the Weave GitOps Enterprise UI on the management cluster:

```yaml title="remote-cluster-service-user-rbac.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: user-groups-impersonator
rules:
  - apiGroups: [""]
    resources: ["users", "groups"]
    verbs: ["impersonate"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list"]
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: impersonate-user-groups
subjects:
  - kind: ServiceAccount
    name: remote-cluster-01  # Service account created in remote cluster
    namespace: default
roleRef:
  kind: ClusterRole
  name: user-groups-impersonator
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: canary-reader
rules:
  - apiGroups: [""]
    resources: [ "events", "services" ]
    verbs: [ "get", "list", "watch" ]
  - apiGroups: [ "apps" ]
    resources: [ "*" ]
    verbs: [ "get", "list" ]
  - apiGroups: [ "autoscaling" ]
    resources: [ "*" ]
    verbs: [ "get", "list" ]
  - apiGroups: [ "flagger.app" ]
    resources: [ "canaries", "metrictemplates"]
    verbs: [ "get", "list", "watch" ]
  - apiGroups: [ "helm.toolkit.fluxcd.io" ]
    resources: [ "helmreleases" ]
    verbs: [ "get", "list" ]
  - apiGroups: [ "kustomize.toolkit.fluxcd.io" ]
    resources: [ "kustomizations" ]
    verbs: [ "get", "list" ]
  - apiGroups: [ "source.toolkit.fluxcd.io" ]
    resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
    verbs: [ "get", "list" ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-canaries
subjects:
- kind: User
  name: wego-admin    # User logged in management cluster, impersonated via service account
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: canary-reader
  apiGroup: rbac.authorization.k8s.io
```

You may need to add more users/groups to the `read-canaries` ClusterRoleBinding to ensure additional users can view canary information from within the Weave GitOps Enterprise UI.